home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.053 < prev    next >
Encoding:
Text File  |  1991-06-28  |  13.6 KB  |  308 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #53:         Desk Accessories and Tools
  9.  
  10. Revised by:  Dave "Out of Phase" Lyons                             March 1991
  11. Written by:  Matt Deatherage & Jim Mensch                          March 1989
  12.  
  13. This Technical Note discusses compatibility issues that can arise betweendesk 
  14. accessories and applications.  Where possible, it presents solutions.
  15.  
  16. Changes since September 1990:  Rewrote much of note to be explicit and 
  17. concise.
  18. _____________________________________________________________________________
  19.  
  20.  
  21. This Note presents guidelines to help applications and desk accessories work
  22. together smoothly.
  23.  
  24. Tool Sets
  25.  
  26. The greatest conflict between applications and desk accessories, especially 
  27. NDAs, is the use of system tool sets.  The Apple IIgs Toolbox 
  28. Reference,Volume 1, defines the minimum collection of tools sets available to 
  29. an NDA.  TheDesk Manager requires that an application start the following 
  30. tool sets before calling DeskStartUp:
  31.  
  32.     Tool Locator (#1)
  33.     Memory Manager (#2)
  34.     Miscellaneous Tools (#3)
  35.     QuickDraw II (#4)
  36.     Event Manager (#6)
  37.     Window Manager (#14)
  38.     Menu Manager (#15)
  39.     Control Manager (#16)
  40.     LineEdit (#20)
  41.     Dialog Manager (#21)
  42.     Scrap Manager (#22)
  43.  
  44. NDAs may assume that these tools are all present and running, so they do not
  45. need to check for their presence.  NDAs can also use the following tool sets
  46. without special consideration for starting them up:  Desk Manager, Scheduler,
  47. Apple Desktop Bus, and Integer Math.
  48.  
  49. In addition to the tool sets applications must start to support NDAs, Apple
  50. recommends that applications start the following tools:
  51.  
  52.     QuickDraw Auxiliary (#18)
  53.     Font Manager (#27)
  54.  
  55. These two additional tools are so widely used by desk accessories that they 
  56. should be present.  NDAs may not assume their presence, but it is 
  57. reasonableto write an NDA that checks for them, with the assumption that they 
  58. usually turn out to be available.
  59.  
  60.  
  61. NDA Guidelines
  62.  
  63. Which Tool Sets Can An NDA Use?
  64.  
  65. o   In general, NDAs can use the tool sets which have already been started up
  66.     by the host application, even tools that are not guaranteed to be started
  67.     up. Using other tool sets is trickier (see below).
  68.  
  69. o   In general, NDAs should not start up tools that are already started up.
  70.     (The Resource Manager is an exception.)
  71.  
  72. o   The Resource Manager must be started separately by each client.  See
  73.     Apple IIgs Technical Note #71 for detailed information on using the 
  74.     Resource Manager from an NDA.
  75.  
  76. o   Sound tools are an exception to the rule of freely using a tool which is
  77.     already started. See the section "Sound Tools" sections later in this 
  78.     note.
  79.  
  80. o   Some tool sets are easily started up each time they are needed, if they
  81.     are not already present.
  82.  
  83.     Standard File is an excellent example.  If an NDA needs to use Standard
  84.     File, it should check to see if the tool is already running.  If it is
  85.     not running, the NDA must use LoadOneTool to load it, then it must
  86.     allocate a page of direct-page space and start the tool before using it. 
  87.     When finished with the tool, the NDA must shut it down, deallocate the
  88.     direct-page space, and unload it with UnloadOneTool.  (A tool is already
  89.     running if its xxxStatus function returns TRUE and does not return an
  90.     error.)
  91.  
  92.     The important thing here is that the NDA shuts down Standard File
  93.     immediately after using it, if it was not already started.  This does not
  94.     cause conflicts with the host application or with other NDAs.
  95.  
  96.     Note that by pre-initializing the result space of an xxxStatus call to
  97.     zero, you can avoid caring whether the tool is present but not started or
  98.     simply not present.
  99.  
  100.         pea $0000
  101.         _SFStatus
  102.         pla     ;A is nonzero if Standard File is started
  103.  
  104.     From a high-level language, you may not be able to pre-initialize the
  105.     result space.  Instead, you need something like the C statement:
  106.  
  107.         StdFileActive = ( SFStatus() && !_toolErr);
  108.  
  109.     or the Pascal statement:
  110.  
  111.         StdFileActive := (SFStatus<>0) AND (ToolErrorNum=0);
  112.  
  113. o   It is impractical or impossible to start up certain tool sets each time
  114.     they are needed.  These include the Font Manager, Scrap Manager, and Text
  115.     Edit.
  116.  
  117.     If an NDA needs to start up a tool and keep it started while letting the
  118.     application continue to run, things get interesting.  (There is a risk
  119.     that the host application will later try to start up the tool set itself
  120.     and not be able to deal with the tool already being started.)
  121.  
  122.     In practice, the safest thing you can do for a tool you need to leave
  123.     running is:
  124.  
  125.         When your NDA is opened, check the tool set's status.  If it is not
  126.         available, use LoadOneTool, allocate any needed direct-page space,
  127.         start up the tool set, and set a flag indicating that your NDA
  128.         started the tool set.
  129.  
  130.         When your NDA's Init routine is called at DeskShutDown time
  131.         (Accumulator equal to zero), check the flag set above.  If your NDA
  132.         started a tool set, shut it down, dispose of any direct-page space
  133.         you allocated for it, and call UnloadOneTool.
  134.  
  135.         (Keep in mind that your NDA can be opened and closed many times
  136.         before DeskShutDown is called when the application finally quits.  If
  137.         you have started a tool and set a flag on an open, be sure not to
  138.         disturb the flag on a future open, when the tool is already available
  139.         because you started it!  You still need to shut it down at
  140.         DeskShutDown time.)
  141.  
  142.         Do not shut down tool sets when your NDA is closed.  To see why,
  143.         consider what would happen if two NDAs just like yours were used at
  144.         the same time. If the NDAs were closed in any other than the exact
  145.         opposite order they were opened, some NDAs would have tool sets shut
  146.         down from underneath them.
  147.  
  148. StartUpTools
  149.  
  150. o   StartUpTools in System Software 5.0.4 and earlier is designed to be 
  151.     called only by an application, not a desk accessory.  Unexpected things 
  152.     happen if your NDA calls StartUpTools (for example, you may get a second 
  153.     copy of the application's resource fork open in your NDA's private 
  154.     resource search path; this wastes RAM and can interfere with an 
  155.     application's attempt to write to its own resource fork).  For now, do 
  156.     not call StartUpTools from a desk accessory.
  157.  
  158. TLStartUp and TLShutDown
  159.  
  160. o   Do not call TLStartUp or TLShutDown from a desk accessory.
  161.  
  162. o   You may call MMStartUp at any time to get your desk accessory's own 
  163.     memory ID.  This does not allocate a new ID; it just tells you what ID 
  164.     you already have (it returns the memory ID of the block the MMStartUp 
  165.     call is made from).
  166.  
  167. User Tool Sets Belong to the Application
  168.  
  169. o   A desk accessory must not install user tool sets, because there is no
  170.     arbitration of user tool set numbers.  User tool sets are the sole
  171.     property of the current application.
  172.  
  173.     A desk accessory should not call user tool sets even if it determines
  174.     that the host application has installed a certain tool set, because that 
  175.     limits future system software options.  For example, consider a 
  176.     hypothetical multiple-application environment.  If DAs call user tool 
  177.     sets and the system automatically switches between separate collections 
  178.     of user tool sets, there would be no way for the system to know which set 
  179.     to switch in before giving control to a desk accessory.
  180.  
  181. Bank Zero Memory and Error $0201
  182.  
  183. o   If you get error $0201 (unable to allocate memory block) while trying to
  184.     launch a ProDOS 8 application, it is probably because your NDA allocated
  185.     some memory in bank 0 or bank 1 and failed to dispose of it at
  186.     DeskShutDown time (when the NDA's Init routine is called with the
  187.     accumulator equal to zero).  GS/OS needs to allocate all of this memory
  188.     for ProDOS 8 to use.
  189.  
  190. QuickDraw Auxiliary
  191.  
  192. o   Starting QuickDraw Auxiliary when the application has not started it can
  193.     be a problem.  An application that correctly implements switching between
  194.     320 and 640 mode calls QDShutDown and QDStartUp.  QuickDraw Auxiliary
  195.     depends heavily on QuickDraw, and restarting QuickDraw while QuickDraw
  196.     Auxiliary is active will fry big-time.  (This behavior will probably be
  197.     removed in future system software.)
  198.  
  199.  
  200. Sound Tools
  201.  
  202. o   A desk accessory cannot use any of the sound tools if they are already
  203.     started.  This is contrary to the rule for other tool sets, but it is
  204.     required because there is no memory management of the sound RAM (or "DOC
  205.     RAM").  If the Sound Tools (#8) are started, the application has 
  206.     exclusive control of the 64K DOC RAM used to play sounds.  Anything your 
  207.     desk accessory might put there could overwrite information the 
  208.     application needs.
  209.  
  210.     Saving and restoring DOC RAM around desk accessory usage is not
  211.     sufficient.  Many of the sound functions are interrupt driven, altering
  212.     the contents of DOC RAM only during sound interrupts, so your desk
  213.     accessory might attempt to replace parts of DOC RAM which are being
  214.     played.  Since there is no memory management of DOC RAM, desk accessories
  215.     must avoid the sound functions of the IIgs if the application is already
  216.     using them.
  217.  
  218.  
  219. Application Guidelines
  220.  
  221. For best compatibility with NDAs, applications should follow the following
  222. guidelines.
  223.  
  224. o   Be careful about when your application starts and shuts down tools.  A
  225.     highly compatible approach is to start tools at the beginning of your
  226.     application and leave them started.  For certain tools, like Standard
  227.     File, it is reasonable to load and start the tool set each time it's
  228.     needed (you may want to check whether it's already started, in case some
  229.     impolite NDA started Standard File and left it started).
  230.  
  231.     Note that UnloadOneTool followed later by LoadOneTool does not
  232.     necessarily cause disk access or ask the user to insert the boot disk.
  233.     UnloadOneTool calls UserShutDown to put the tool set into "zombie" state,
  234.     where it can be restarted from memory if none of its segments have been
  235.     purged.  Unloading tools while they aren't in use is a Good Thing if the
  236.     user has plenty of RAM, there's no noticeable performance hit, but if RAM
  237.     space is tight then doing extra disk access still is preferable to
  238.     actually running out of memory.
  239.  
  240.     For maximum compatibility, an application should not shut down any tools
  241.     which were ever active when it called SystemTask or TaskMaster (until
  242.     quitting time, of course, when it shuts down everything, starting with 
  243.     the Desk Manager).  The application can start more tools, but it should 
  244.     not shut down those which are already active.
  245.  
  246.     If your application is going to start a tool and not keep it started, use
  247.     it and then shut it down immediately, without allowing desk accessories 
  248.     to be opened during that time.
  249.  
  250. o   Don't just start the Scrap Manager use it!  Many desk accessories
  251.     support cutting and pasting to exchange text and pictures with your
  252.     application, but they can do it only if you use the Scrap Manager.  If
  253.     you have a need for your own private scrap internally, you should still
  254.     also use the Scrap Manager to exchange text and pictures with other
  255.     applications and DAs.
  256.  
  257. o   Provide an Edit menu, and when an NDA window comes to the front enable 
  258.     the menu and the Undo, Cut, Copy, Paste, and Clear items.
  259.  
  260. o   Applications should never make a Close call with reference number zero at
  261.     file level zero.  (If you need to use Close with reference number zero,
  262.     use GetLevel and SetLevel to avoid closing files you did not open.)
  263.  
  264.     DAs written recently can open their files at an internal file level, as
  265.     documented in GS/OS Technical Note #13, but applications still need to
  266.     avoid closing all files at level zero for compatibility with older desk
  267.     accessories.
  268.  
  269. o   An application with some memory to spare can save NDAs time by providing
  270.     them the additional tools which they are most likely to use.
  271.  
  272.     The most common tools which desk accessories require besides those
  273.     available in the standard Desk Manager set are QuickDraw Auxiliary (#18),
  274.     the Print Manager (#19), Standard File (#23), the Font Manager (#27), and
  275.     the List Manager (#28).
  276.  
  277. o   When you call TaskMaster or GetNextEvent, or EventAvail, be sure bit
  278.     10 is turned on in the event mask, to enable "desk accessory" events.
  279.     If you turn this bit off, users will not be able to get to the
  280.     Classic Desk Accessory menu by pressing Apple-Ctrl-ESC.
  281.  
  282. CDA Guidelines
  283.  
  284. o   CDAs are nearly always modal, but by using the HeartBeat interrupt queue
  285.     or other mechanisms, they can get control when the user is no longer "in"
  286.     the CDA.  The list of guaranteed tools for NDAs does not apply to CDAs,
  287.     and CDAs must be prepared to deal with the ProDOS 8 environment as well 
  288.     as GS/OS.
  289.  
  290. o   Under ProDOS 8, a CDA will not be able to allocate any bank 0 space
  291.     through the Memory Manager; it can only use page 0 and page 1 safely (the
  292.     stack is in page 1).
  293.  
  294. o   Do not call TLStartUp or TLShutDown from a desk accessory.
  295.  
  296. o   You may call MMStartUp at any time to get your DA's own memory ID.  This
  297.     does not allocate a new ID; it just tells you what ID you already have
  298.     (it returns the memory ID of the block the MMStartUp call is made from).
  299.  
  300.  
  301. Further Reference
  302. _____________________________________________________________________________
  303.   o  Apple IIgs Toolbox Reference
  304.   o  Programmer's Introduction to the Apple IIgs
  305.   o  Apple IIgs Technical Note #71, Desk Accessory Tips and Techniques
  306.   o  Apple IIgs Technical Note #83, Resource Manager Stuff
  307.  
  308.